| 1 | /* $NetBSD: vstream.c,v 1.2 2017/02/14 01:16:49 christos Exp $ */ |
| 2 | |
| 3 | /*++ |
| 4 | /* NAME |
| 5 | /* vstream 3 |
| 6 | /* SUMMARY |
| 7 | /* light-weight buffered I/O package |
| 8 | /* SYNOPSIS |
| 9 | /* #include <vstream.h> |
| 10 | /* |
| 11 | /* VSTREAM *vstream_fopen(path, flags, mode) |
| 12 | /* const char *path; |
| 13 | /* int flags; |
| 14 | /* mode_t mode; |
| 15 | /* |
| 16 | /* VSTREAM *vstream_fdopen(fd, flags) |
| 17 | /* int fd; |
| 18 | /* int flags; |
| 19 | /* |
| 20 | /* int vstream_fclose(stream) |
| 21 | /* VSTREAM *stream; |
| 22 | /* |
| 23 | /* int vstream_fdclose(stream) |
| 24 | /* VSTREAM *stream; |
| 25 | /* |
| 26 | /* VSTREAM *vstream_printf(format, ...) |
| 27 | /* const char *format; |
| 28 | /* |
| 29 | /* VSTREAM *vstream_fprintf(stream, format, ...) |
| 30 | /* VSTREAM *stream; |
| 31 | /* const char *format; |
| 32 | /* |
| 33 | /* int VSTREAM_GETC(stream) |
| 34 | /* VSTREAM *stream; |
| 35 | /* |
| 36 | /* int VSTREAM_PUTC(ch, stream) |
| 37 | /* int ch; |
| 38 | /* |
| 39 | /* int VSTREAM_GETCHAR(void) |
| 40 | /* |
| 41 | /* int VSTREAM_PUTCHAR(ch) |
| 42 | /* int ch; |
| 43 | /* |
| 44 | /* int vstream_ungetc(stream, ch) |
| 45 | /* VSTREAM *stream; |
| 46 | /* int ch; |
| 47 | /* |
| 48 | /* int vstream_fputs(str, stream) |
| 49 | /* const char *str; |
| 50 | /* VSTREAM *stream; |
| 51 | /* |
| 52 | /* off_t vstream_ftell(stream) |
| 53 | /* VSTREAM *stream; |
| 54 | /* |
| 55 | /* off_t vstream_fseek(stream, offset, whence) |
| 56 | /* VSTREAM *stream; |
| 57 | /* off_t offset; |
| 58 | /* int whence; |
| 59 | /* |
| 60 | /* int vstream_fflush(stream) |
| 61 | /* VSTREAM *stream; |
| 62 | /* |
| 63 | /* int vstream_fpurge(stream, direction) |
| 64 | /* VSTREAM *stream; |
| 65 | /* int direction; |
| 66 | /* |
| 67 | /* ssize_t vstream_fread(stream, buf, len) |
| 68 | /* VSTREAM *stream; |
| 69 | /* void *buf; |
| 70 | /* ssize_t len; |
| 71 | /* |
| 72 | /* ssize_t vstream_fwrite(stream, buf, len) |
| 73 | /* VSTREAM *stream; |
| 74 | /* const void *buf; |
| 75 | /* ssize_t len; |
| 76 | /* |
| 77 | /* void vstream_control(stream, name, ...) |
| 78 | /* VSTREAM *stream; |
| 79 | /* int name; |
| 80 | /* |
| 81 | /* int vstream_fileno(stream) |
| 82 | /* VSTREAM *stream; |
| 83 | /* |
| 84 | /* const ssize_t vstream_req_bufsize(stream) |
| 85 | /* VSTREAM *stream; |
| 86 | /* |
| 87 | /* void *vstream_context(stream) |
| 88 | /* VSTREAM *stream; |
| 89 | /* |
| 90 | /* int vstream_ferror(stream) |
| 91 | /* VSTREAM *stream; |
| 92 | /* |
| 93 | /* int vstream_ftimeout(stream) |
| 94 | /* VSTREAM *stream; |
| 95 | /* |
| 96 | /* int vstream_feof(stream) |
| 97 | /* VSTREAM *stream; |
| 98 | /* |
| 99 | /* int vstream_clearerr(stream) |
| 100 | /* VSTREAM *stream; |
| 101 | /* |
| 102 | /* const char *VSTREAM_PATH(stream) |
| 103 | /* VSTREAM *stream; |
| 104 | /* |
| 105 | /* char *vstream_vprintf(format, ap) |
| 106 | /* const char *format; |
| 107 | /* va_list *ap; |
| 108 | /* |
| 109 | /* char *vstream_vfprintf(stream, format, ap) |
| 110 | /* VSTREAM *stream; |
| 111 | /* const char *format; |
| 112 | /* va_list *ap; |
| 113 | /* |
| 114 | /* ssize_t vstream_bufstat(stream, command) |
| 115 | /* VSTREAM *stream; |
| 116 | /* int command; |
| 117 | /* |
| 118 | /* ssize_t vstream_peek(stream) |
| 119 | /* VSTREAM *stream; |
| 120 | /* |
| 121 | /* const char *vstream_peek_data(stream) |
| 122 | /* VSTREAM *stream; |
| 123 | /* |
| 124 | /* int vstream_setjmp(stream) |
| 125 | /* VSTREAM *stream; |
| 126 | /* |
| 127 | /* void vstream_longjmp(stream, val) |
| 128 | /* VSTREAM *stream; |
| 129 | /* int val; |
| 130 | /* |
| 131 | /* time_t vstream_ftime(stream) |
| 132 | /* VSTREAM *stream; |
| 133 | /* |
| 134 | /* struct timeval vstream_ftimeval(stream) |
| 135 | /* VSTREAM *stream; |
| 136 | /* |
| 137 | /* int vstream_rd_error(stream) |
| 138 | /* VSTREAM *stream; |
| 139 | /* |
| 140 | /* int vstream_wr_error(stream) |
| 141 | /* VSTREAM *stream; |
| 142 | /* |
| 143 | /* int vstream_rd_timeout(stream) |
| 144 | /* VSTREAM *stream; |
| 145 | /* |
| 146 | /* int vstream_wr_timeout(stream) |
| 147 | /* VSTREAM *stream; |
| 148 | /* |
| 149 | /* int vstream_fstat(stream, flags) |
| 150 | /* VSTREAM *stream; |
| 151 | /* int flags; |
| 152 | /* DESCRIPTION |
| 153 | /* The \fIvstream\fR module implements light-weight buffered I/O |
| 154 | /* similar to the standard I/O routines. |
| 155 | /* |
| 156 | /* The interface is implemented in terms of VSTREAM structure |
| 157 | /* pointers, also called streams. For convenience, three streams |
| 158 | /* are predefined: VSTREAM_IN, VSTREAM_OUT, and VSTREAM_ERR. These |
| 159 | /* streams are connected to the standard input, output and error |
| 160 | /* file descriptors, respectively. |
| 161 | /* |
| 162 | /* Although the interface is patterned after the standard I/O |
| 163 | /* library, there are some major differences: |
| 164 | /* .IP \(bu |
| 165 | /* File descriptors are not limited to the range 0..255. This |
| 166 | /* was reason #1 to write these routines in the first place. |
| 167 | /* .IP \(bu |
| 168 | /* The application can switch between reading and writing on |
| 169 | /* the same stream without having to perform a flush or seek |
| 170 | /* operation, and can change write position without having to |
| 171 | /* flush. This was reason #2. Upon position or direction change, |
| 172 | /* unread input is discarded, and unwritten output is flushed |
| 173 | /* automatically. Exception: with double-buffered streams, unread |
| 174 | /* input is not discarded upon change of I/O direction, and |
| 175 | /* output flushing is delayed until the read buffer must be refilled. |
| 176 | /* .IP \(bu |
| 177 | /* A bidirectional stream can read and write with the same buffer |
| 178 | /* and file descriptor, or it can have separate read/write |
| 179 | /* buffers and/or file descriptors. |
| 180 | /* .IP \(bu |
| 181 | /* No automatic flushing of VSTREAM_OUT upon program exit, or of |
| 182 | /* VSTREAM_ERR at any time. No unbuffered or line buffered modes. |
| 183 | /* This functionality may be added when it is really needed. |
| 184 | /* .PP |
| 185 | /* vstream_fopen() opens the named file and associates a buffered |
| 186 | /* stream with it. The \fIpath\fR, \fIflags\fR and \fImode\fR |
| 187 | /* arguments are passed on to the open(2) routine. The result is |
| 188 | /* a null pointer in case of problems. The \fIpath\fR argument is |
| 189 | /* copied and can be looked up with VSTREAM_PATH(). |
| 190 | /* |
| 191 | /* vstream_fdopen() takes an open file and associates a buffered |
| 192 | /* stream with it. The \fIflags\fR argument specifies how the file |
| 193 | /* was opened. vstream_fdopen() either succeeds or never returns. |
| 194 | /* |
| 195 | /* vstream_fclose() closes the named buffered stream. The result |
| 196 | /* is 0 in case of success, VSTREAM_EOF in case of problems. |
| 197 | /* vstream_fclose() reports the same errors as vstream_ferror(). |
| 198 | /* |
| 199 | /* vstream_fdclose() leaves the file(s) open but is otherwise |
| 200 | /* identical to vstream_fclose(). |
| 201 | /* |
| 202 | /* vstream_fprintf() formats its arguments according to the |
| 203 | /* \fIformat\fR argument and writes the result to the named stream. |
| 204 | /* The result is the stream argument. It understands the s, c, d, u, |
| 205 | /* o, x, X, e, f and g format types, the l modifier, field width and |
| 206 | /* precision, sign, and padding with zeros or spaces. In addition, |
| 207 | /* vstream_fprintf() recognizes the %m format specifier and expands |
| 208 | /* it to the error message corresponding to the current value of the |
| 209 | /* global \fIerrno\fR variable. |
| 210 | /* |
| 211 | /* vstream_printf() performs formatted output to the standard output |
| 212 | /* stream. |
| 213 | /* |
| 214 | /* VSTREAM_GETC() reads the next character from the named stream. |
| 215 | /* The result is VSTREAM_EOF when end-of-file is reached or if a read |
| 216 | /* error was detected. VSTREAM_GETC() is an unsafe macro that |
| 217 | /* evaluates some arguments more than once. |
| 218 | /* |
| 219 | /* VSTREAM_GETCHAR() is an alias for VSTREAM_GETC(VSTREAM_IN). |
| 220 | /* |
| 221 | /* VSTREAM_PUTC() appends the specified character to the specified |
| 222 | /* stream. The result is the stored character, or VSTREAM_EOF in |
| 223 | /* case of problems. VSTREAM_PUTC() is an unsafe macro that |
| 224 | /* evaluates some arguments more than once. |
| 225 | /* |
| 226 | /* VSTREAM_PUTCHAR(c) is an alias for VSTREAM_PUTC(c, VSTREAM_OUT). |
| 227 | /* |
| 228 | /* vstream_ungetc() pushes back a character onto the specified stream |
| 229 | /* and returns the character, or VSTREAM_EOF in case of problems. |
| 230 | /* It is an error to push back before reading (or immediately after |
| 231 | /* changing the stream offset via vstream_fseek()). Upon successful |
| 232 | /* return, vstream_ungetc() clears the end-of-file stream flag. |
| 233 | /* |
| 234 | /* vstream_fputs() appends the given null-terminated string to the |
| 235 | /* specified buffered stream. The result is 0 in case of success, |
| 236 | /* VSTREAM_EOF in case of problems. |
| 237 | /* |
| 238 | /* vstream_ftell() returns the file offset for the specified stream, |
| 239 | /* -1 if the stream is connected to a non-seekable file. |
| 240 | /* |
| 241 | /* vstream_fseek() changes the file position for the next read or write |
| 242 | /* operation. Unwritten output is flushed. With unidirectional streams, |
| 243 | /* unread input is discarded. The \fIoffset\fR argument specifies the file |
| 244 | /* position from the beginning of the file (\fIwhence\fR is SEEK_SET), |
| 245 | /* from the current file position (\fIwhence\fR is SEEK_CUR), or from |
| 246 | /* the file end (SEEK_END). The result value is the file offset |
| 247 | /* from the beginning of the file, -1 in case of problems. |
| 248 | /* |
| 249 | /* vstream_fflush() flushes unwritten data to a file that was |
| 250 | /* opened in read-write or write-only mode. |
| 251 | /* vstream_fflush() returns 0 in case of success, VSTREAM_EOF in |
| 252 | /* case of problems. It is an error to flush a read-only stream. |
| 253 | /* vstream_fflush() reports the same errors as vstream_ferror(). |
| 254 | |
|---|